[% setvar title Subroutines should be able to return an lvalue %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Subroutines should be able to return an lvalue</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Johan Vromans &lt;<a href='mailto:jvromans@squirrel.nl'>jvromans@squirrel.nl</a>&gt;
  Date: 18 Aug 2000
  Last Modified: 20 Sep 2000
  Mailing List: <a href='mailto:perl6-language-subs@perl.org'>perl6-language-subs@perl.org</a>
  Number: 132
  Version: 4
  Status: Frozen</pre>
<a name='NOTE'></a><h1>NOTE</h1>
<p>See CHANGES for wrap-up info.</p>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>RFC 107 proposes that lvalue subs should receive their rvalues as
subroutine arguments. RFC 118 counter-proposes that lvalue subs should
receive their rvalues as lexical variables named in a prototype
associated with the :lvalue modifier. This RFC proposes a terrifying
simple solution for the growing complexity of the lvalue subroutines
problem. It proposes the keyword <code>lreturn</code> and discards the &lt;:lvalue&gt;
property.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>If a sub wants to return an lvalue, this lvalue must be a real lvalue
in all respects. In particular, all kinds of implicit and explicit
value changes must be supported. For example,</p>
<pre>    lvsub() = ...
    lvsub()++;
    lvsub() += ...
    lvsub() =~ s///
    for ( lvsub() ) {
        $_ = ...
    }
    sysread($fh,lvsub(),...)
    substr(lvsub(),...) = ...</pre>
<p>and so on.</p>
<p>One often heard argument is that subroutines like these must be
callable in either mode:</p>
<pre>    lvsub(expr)
    lvsub() = expr</pre>
<p>and that therefore &quot;lvsub() = expr&quot; is mere syntactic sugar for
&quot;lvsub(expr)&quot;. This argument is false, since the two uses are totally
distinct. In the first case, the sub has control over what it does
with the value while in the lvalue case the sub doesn't -- and doesn't
care. If control is desired, use <code>tie</code>.</p>
<p>The clue is &quot;If a sub wants to return an lvalue, what's returned must
really be an lvalue&quot;. Therefore I propose a new keyword <code>lreturn</code>
that behaves just like <code>return</code>, but returns the lvalue instead of
the rvalue. After returning, everything is exactly as if the argument
to lreturn were specified instead of the subroutine call. The
&lt;:lvalue&gt; property is no longer needed and should be removed since it
only causes confusion. A subroutine <b>is</b> not an lvalue thing, it
<b>returns</b> an lvalue if it wants to.</p>
<p>For example:</p>
<pre>    sub lvsub {
       ...
       lreturn $hash{somekey};
    }

    lvsub() =~ s///    # identical to $hash{somekey} =~ s///
    $ref = \lvsub()    # now $ref is \$hash{somekey}</pre>
<p>As a thought guide: think of <code>lreturn</code> returning a reference to its
argument, and the call to lvsub() performing a dereference.</p>
<p>With the enhanced <code>want</code> operator, subroutines can dynamically decide
what to return.</p>
<p>Interesting note: you can always use <code>lreturn</code> instead of <code>return</code>;
for rvalue cases it does not matter.</p>
<a name='FUNDAMENTAL RESTRICTION'></a><h1>FUNDAMENTAL RESTRICTION</h1>
<p>There aint no such thing as a free lunch, so there's a catch.</p>
<p>Good programming practice requires that, in assignments, the right
hand side gets evaluated before the left hand side. This is to make
statements like</p>
<pre>    $a[$i++] = $b[$i++]</pre>
<p>have a defined semantics. This principle enforces a restriction to
subroutines that want to return an lvalue. Consider</p>
<pre>    lvsub() = some_sub()</pre>
<p>The problem is to determine the context in which some_sub() must be
called. While with normal assignments this context is always clear, in
this example the context is determined by what lvsub is going to
lreturn, <i>which is not going to happen before some_sub() has
completed</i>. The only solution seems to be to restrict lvalue
subroutines to return only scalar lvalues.</p>
<p>Subroutine prototypes and/or attributes are often suggested as a means
to overcome this restriction. However, due to the powers of Perl this
is impossible. For example, consider sub <code>foo</code> that returns an array
lvalue, and sub <code>bar</code> that returns a scalar lvalue. Even when
prototyped or attributed, the following construction will cause
problems:</p>
<pre>    my $ref = $some_condition ? \&amp;foo : \&amp;bar;
    $ref-&gt;() = some_sub();</pre>
<p>Another attempt to overcome this restriction is to change the
evaluation order of assignments, probably only in case an lvalued sub
is involved. I prefer not to consider this an option, but maybe others
feel differently.</p>
<p>Therefore the restriction of <code>lreturn</code> to scalar lvalues must be
considered a fundamental one. Fortunately, this restriction is not a
problematic one. Scalars are already &quot;more than common&quot; in Perl. For
example, arrays and hashes can only contain scalars, and nobody has
ever considered that a problem. References rulez!</p>
<a name='COMPATIBILITY'></a><h1>COMPATIBILITY</h1>
<p>The proposed solution is upward compatible with the current Perl5
implementation of lvalued subroutines:</p>
<pre>    sub foo : lvalue { ...; $var }</pre>
<p>can be interpreted as a shorthand, or syntactic sugar, for</p>
<pre>    sub foo { ...; lreturn $var }</pre>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>Every subroutine (and method) call can potentially return an lvalue,
so the compiler cannot do smart things. All must be handled at
run-time.</p>
<a name='CHANGES'></a><h1>CHANGES</h1>
<a name='Version 4, 20 September 2000'></a><h2>Version 4, 20 September 2000</h2>
<p>Frozen after some discussions on the mailing list. People seem to be
divided in two groups. One group considers an lvalue return solely for
assignment, and hence propose to add an additional magical parameter
to lvalue routines. Other RFCs deal with that approach. The other
group joins me in the opinion that lvalue means, in essence,
equivalence to a variable. This RFC is for them.</p>
<a name='Version 4'></a><h2>Version 4</h2>
<p>Added CHANGES section.</p>
<p>Clarified the syntactic sugar misconception.</p>
<a name='Version 3, Aug 28 2000'></a><h2>Version 3, Aug 28 2000</h2>
<p>Add Status indicator.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 107: lvalue subs should receive the rvalue as an argument</p>
<p>RFC 118: lvalue subs: parameters, explicit assignment, and wantarray() changes</p>
<p>NRETURN, &quot;The SNOBOL4 Programming Language&quot;, Griswold &amp; Polonsky.</p>
<p>RFC 21: Replace <code>wantarray</code> with a generic <code>want</code> function</p>
</div>
